hetzner Api docs.md --------------- For: https://docs.hetzner.cloud/reference/hetzner reference for Api docs: hetzner.com --- Hetzner API Overview This is the official documentation for the Hetzner API. Introduction The Hetzner API operates over HTTPS and uses JSON as its data format. The API is a RESTful API and utilizes HTTP methods and HTTP status codes to specify requests and responses. Open source credits If you are developing an open-source project that supports or intends to add support for Hetzner APIs, you may be eligible for a free one-time credit of up to € 50 / $ 50 on your account. Please contact us via the support page on your Console and let us know the following: The name of the project you are working on A short description of the project Link to the project website or repo where the project is hosted Affiliation with / role in the project (e.g. project maintainer) Link to some other open-source work you have already done (if you have done so) Note: We only consider rewards for projects that provide Hetzner-specific functionality or integrations. For example, our Object Storage exposes a standard S3 API without any Hetzner-specific extensions. Projects that focus solely on generic S3 capabilities (e.g., general S3 clients or SDKs) are not Hetzner-specific and are therefore not eligible for Hetzner Rewards. Getting Started To get started using the API you first need an API token. Sign in into the Hetzner Console choose a Project, go to Security → API Tokens, and generate a new token. Make sure to copy the token because it won’t be shown to you again. A token is bound to a Project, to interact with the API of another Project you have to create a new token inside the Project. Let’s say your new token is LRK9DAWQ1ZAEFSrCNEEzLCUwhYX1U3g7wMg4dTlkkDC96fyDuyJ39nVbVjCKSDfj. You’re now ready to do your first request against the API. To get a list of all Storage Boxes in your Project, issue the example request on the right side using curl. Make sure to replace the token in the example command with the token you have just created. Since your Project probably does not contain any Storage Boxes yet, the example response will look like the response on the right side. We will almost always provide a resource root like storage_boxes inside the example response. A response can also contain a meta object with information like Pagination. Example Request curl -H "Authorization: Bearer LRK9DAWQ1ZAEFSrCNEEzLCUwhYX1U3g7wMg4dTlkkDC96fyDuyJ39nVbVjCKSDfj" \ https://api.hetzner.com/v1/storage_boxes Example Response { "storage_boxes": [], "meta": { "pagination": { "page": 1, "per_page": 25, "previous_page": null, "next_page": null, "last_page": 1, "total_entries": 0 } } } Authentication All requests to the Hetzner API must be authenticated via a API token. Include your secret API token in every request you send to the API with the Authorization HTTP header. To create a new API token for your Project, switch into the Hetzner Console choose a Project, go to Security → API Tokens, and generate a new token. Example Authorization header Authorization: Bearer LRK9DAWQ1ZAEFSrCNEEzLCUwhYX1U3g7wMg4dTlkkDC96fyDuyJ39nVbVjCKSDfj Query Parameters The API makes use of query parameters to sort and filter responses. The parameter names and values must be URI encoded according to RFC2396. Query parameters of type array can be used multiple times: Example query parameters for pagination https://api.hetzner.com/v1/storage_boxes?page=1&page_size=12 Example use of multiple values for a parameter https://api.hetzner.com/v1/storage_boxes?sort=id&sort=name Example use of an encoded parameter https://api.hetzner.com/v1/storage_boxes?label_selector=key%3Dvalue Errors Errors are indicated by HTTP status codes. Further, the response of the request which generated the error contains an error code, an error message, and, optionally, error details. The schema of the error details object depends on the error code. The error response contains the following keys: Keys Meaning code Short string indicating the type of error (machine-parsable) message Textual description on what has gone wrong details An object providing for details on the error (schema depends on code) Example response { "error": { "code": "invalid_input", "message": "invalid input in field 'broken_field': is too long", "details": { "fields": [ { "name": "broken_field", "messages": ["is too long"] } ] } } } Error Codes Status Code Description 400 json_error Invalid JSON input in your request. 401 unauthorized Request was made with an invalid or unknown token. 401 token_readonly The token is only allowed to perform GET requests. 403 forbidden Insufficient permissions for this request. 403 maintenance Cannot perform operation due to maintenance. 403 resource_limit_exceeded Error when exceeding the maximum quantity of a resource for an account. 404 not_found Entity not found. 405 method_not_allowed The request method is not allowed 409 uniqueness_error One or more of the objects fields must be unique. 409 conflict The resource has changed during the request, please retry. 410 deprecated_api_endpoint The API endpoint functionality was removed. 412 resource_unavailable The requested resource is currently unavailable (e.g. not available for order). 422 invalid_input Error while parsing or processing the input. 422 service_error Error within a service. 422 unsupported_error The corresponding resource does not support the Action. 423 locked The item you are trying to access is locked (there is already an Action running). 423 protected The Action you are trying to start is protected for this resource. 429 rate_limit_exceeded Error when sending too many requests. 500 server_error Error within the API backend. 502 bad_gateway The request could not be answered by the API backend, please retry. 503 unavailable A service or product is currently not available. 504 timeout The request could not be answered in time, please retry. invalid_input { "error": { "code": "invalid_input", "message": "invalid input in field 'broken_field': is too long", "details": { "fields": [ { "name": "broken_field", "messages": ["is too long"] } ] } } } uniqueness_error { "error": { "code": "uniqueness_error", "message": "SSH key with the same fingerprint already exists", "details": { "fields": [ { "name": "public_key" } ] } } } resource_limit_exceeded { "error": { "code": "resource_limit_exceeded", "message": "project limit exceeded", "details": { "limits": [ { "name": "project_limit" } ] } } } deprecated_api_endpoint { "error": { "code": "deprecated_api_endpoint", "message": "API functionality was removed", "details": { "announcement": "https://docs.hetzner.cloud/changelog#2023-07-20-foo-endpoint-is-deprecated" } } } Actions Actions represent asynchronous tasks within the API, targeting one or more resources. Triggering changes in the API may return a running action. An action should be waited upon, until it reaches either the success or error state. Avoid polling the action's state too frequently to reduce the risk of exhausting your API requests and hitting the rate limit. If an action fails, it will contain details about the underlying error. Once the asynchronous tasks have completed and the targeted resources are in a consistent state, the action is marked as succeeded. In some cases, you may trigger multiple changes at once, and only wait for the returned actions at a later stage. Labels Labels are key/value pairs that can be attached to all resources. Valid label keys have two segments: an optional prefix and name, separated by a slash (/). The name segment is required and must be a string of 63 characters or less, beginning and ending with an alphanumeric character ([a-z0-9A-Z]) with dashes (-), underscores (_), dots (.), and alphanumerics between. The prefix is optional. If specified, the prefix must be a DNS subdomain: a series of DNS labels separated by dots (.), not longer than 253 characters in total, followed by a slash (/). Valid label values must be a string of 63 characters or less and must be empty or begin and end with an alphanumeric character ([a-z0-9A-Z]) with dashes (-), underscores (_), dots (.), and alphanumerics between. The hetzner.cloud/ prefix is reserved and cannot be used. Example Labels { "labels": { "environment": "development", "service": "backend", "example.com/my": "label", "just-a-key": "" } } Label Selector For resources with labels, you can filter resources by their labels using the label selector query language. Expression Meaning k==v / k=v Value of key k does equal value v k!=v Value of key k does not equal value v k Key k is present !k Key k is not present k in (v1,v2,v3) Value of key k is v1, v2, or v3 k notin (v1,v2,v3) Value of key k is neither v1, nor v2, nor v3 k1==v,!k2 Value of key k1 is v and key k2 is not present Examples Returns all resources that have a env=production label and that don't have a type=database label: env=production,type!=database Returns all resources that have a env=testing or env=staging label: env in (testing,staging) Returns all resources that don't have a type label: !type Pagination Responses which return multiple items support pagination. If they do support pagination, it can be controlled with following query string parameters: A page parameter specifies the page to fetch. The number of the first page is 1. A per_page parameter specifies the number of items returned per page. The default value is 25, the maximum value is 50 except otherwise specified in the documentation. Responses contain a Link header with pagination information. Additionally, if the response body is JSON and the root object is an object, that object has a pagination object inside the meta object with pagination information: Example Pagination { "storage_boxes": [...], "meta": { "pagination": { "page": 2, "per_page": 25, "previous_page": 1, "next_page": 3, "last_page": 4, "total_entries": 100 } } } The keys previous_page, next_page, last_page, and total_entries may be null when on the first page, last page, or when the total number of entries is unknown. Example Pagination Link header Link: ; rel="prev", ; rel="next", ; rel="last" Line breaks have been added for display purposes only and responses may only contain some of the above rel values. Rate Limiting All requests, whether they are authenticated or not, are subject to rate limiting. If you have reached your limit, your requests will be handled with a 429 Too Many Requests error. Burst requests are allowed. Responses contain several headers which provide information about your current rate limit status. The RateLimit-Limit header contains the total number of requests you can perform per hour. The RateLimit-Remaining header contains the number of requests remaining in the current rate limit time frame. The RateLimit-Reset header contains a UNIX timestamp of the point in time when your rate limit will have recovered, and you will have the full number of requests available again. The default limit is 3600 requests per hour and per Project. The number of remaining requests increases gradually. For example, when your limit is 3600 requests per hour, the number of remaining requests will increase by 1 every second. Sorting Some responses which return multiple items support sorting. If they do support sorting the documentation states which fields can be used for sorting. You specify sorting with the sort query string parameter. You can sort by multiple fields. You can set the sort direction by appending :asc or :desc to the field name. By default, ascending sorting is used. Example: Sorting https://api.hetzner.com/v1/storage_boxes?sort=status https://api.hetzner.com/v1/storage_boxes?sort=status:asc https://api.hetzner.com/v1/storage_boxes?sort=status:desc https://api.hetzner.com/v1/storage_boxes?sort=status:asc&sort=command:desc Deprecation Notices You can find all announced deprecations in our Changelog. Storage Boxes ​Copy link Storage Boxes offer storage capacity for both small and large amounts of data. Any data you save in your Storage Box is saved on several disks configured in a RAID array, increasing redundancy and fault tolerance. Please see Hetzner Docs for more details about Storage Boxes. Password policy This policy applies to both Storage Boxes and Storage Box Subaccounts. The password must be between 12 and 128 characters long The password can only contain these characters: a-z A-Z Ä Ö Ü ä ö ü ß 0-9 ^ ° ! § $ % / ( ) = ? + # - . , ; : ~ * @ { } _ & The password must contain at least one upper case letter, one lower case letter, one number, and a special character The password must not have appeared in any known data breach Storage BoxesOperations get /storage_boxes post /storage_boxes get /storage_boxes/{id} put /storage_boxes/{id} delete /storage_boxes/{id} get /storage_boxes/{id}/folders List Storage Boxes​Copy link Returns a paginated list of Storage Boxes. Query Parameters nameCopy link to name Type:string Filter resources by their name. The response will only contain the resources matching exactly the specified name. label_selectorCopy link to label_selector Type:string Filter resources by labels. The response will only contain resources matching the label selector. For more information, see "Label Selector". sortCopy link to sort Type:array string[] enum Sort resources by field and direction. May be used multiple times. For more information, see "Sorting". id id:asc id:desc name name:asc Show all values pageCopy link to page Type:integer Format:int64 default: 1 Example Page number to return. For more information, see "Pagination". per_pageCopy link to per_page Type:integer Format:int64 default: 25 Example Maximum number of entries returned per page. For more information, see "Pagination". Responses 200 Request succeeded. application/json 4xx Request failed with a user error. application/json 5xx Request failed with a server error. application/json Request Example for get /storage_boxes Go package examples import ( "context" "os" "github.com/hetznercloud/hcloud-go/v2/hcloud" ) func main() { token := os.Getenv("HCLOUD_TOKEN") client := hcloud.NewClient(hcloud.WithToken(token)) ctx := context.TODO() storageBoxes, err := client.StorageBox.All(ctx) } Status:200 Status:4xx Status:5xx { "storage_boxes": [ { "id": 42, "name": "string", "storage_box_type": { "id": 42, "name": "bx11", "description": "BX11", "snapshot_limit": 10, "automatic_snapshot_limit": 10, "subaccounts_limit": 200, "size": 1073741824, "prices": [ { "location": "fsn1", "price_hourly": { "net": "1.0000", "gross": "1.1900" }, "price_monthly": { "net": "1.0000", "gross": "1.1900" }, "setup_fee": { "net": "1.0000", "gross": "1.1900" } } ], "deprecation": { "unavailable_after": "2023-09-01T00:00:00Z", "announced": "2023-06-01T00:00:00Z" } }, "location": { "id": 42, "name": "fsn1", "description": "Falkenstein DC Park 1", "country": "DE", "city": "Falkenstein", "latitude": 50.47612, "longitude": 12.370071, "network_zone": "eu-central" }, "access_settings": { "reachable_externally": true, "samba_enabled": true, "ssh_enabled": true, "webdav_enabled": true, "zfs_enabled": true }, "snapshot_plan": { "max_snapshots": 10, "minute": 30, "hour": 3, "day_of_week": 7, "day_of_month": null }, "protection": { "delete": false }, "labels": { "environment": "prod", "example.com/my": "label", "just-a-key": "" }, "status": "active", "username": "u12345", "server": "u1337.your-storagebox.de", "system": "FSN1-BX355", "stats": { "size": 1, "size_data": 1, "size_snapshots": 1 }, "created": "2016-01-30T23:55:00Z" } ], "meta": { "pagination": { "page": 3, "per_page": 25, "previous_page": 2, "next_page": 4, "last_page": 4, "total_entries": 100 } } } Create a Storage Box​Copy link Creates a Storage Box. Body required application/json locationCopy link to location Type:string required Example ID or Name of Location. nameCopy link to name Type:string required Name of the Storage Box. passwordCopy link to password Type:string required Password of the Storage Box. For more details, see the Storage Boxes password policy. storage_box_typeCopy link to storage_box_type Type:string required Example ID or Name of the Storage Box Type. access_settingsCopy link to access_settings Type:object Access settings of the Storage Box. Show Child Attributesfor access_settings labelsCopy link to labels Type:object Example User-defined labels (key/value pairs) for the Resource. For more information, see "Labels". Show Child Attributesfor labels ssh_keysCopy link to ssh_keys Type:array string[] Example SSH public keys in OpenSSH format to inject into the Storage Box. Responses 201 Request succeeded. application/json 4xx Request failed with a user error. application/json 5xx Request failed with a server error. application/json Request Example for post /storage_boxes Go package examples import ( "context" "os" "github.com/hetznercloud/hcloud-go/v2/hcloud" ) func main() { token := os.Getenv("HCLOUD_TOKEN") client := hcloud.NewClient(hcloud.WithToken(token)) ctx := context.TODO() result, _, err := client.StorageBox.Create(ctx, hcloud.StorageBoxCreateOpts{ Name: "string", Location: &hcloud.Location{Name: "fsn1"}, StorageBoxType: &hcloud.StorageBoxType{ Name: "bx11", }, Labels: map[string]string{ "environment": "prod", "example.com/my": "label", "just-a-key": "", }, Password: "my-password", AccessSettings: &hcloud.StorageBoxCreateOptsAccessSettings{ ReachableExternally: hcloud.Ptr(false), SambaEnabled: hcloud.Ptr(false), SSHEnabled: hcloud.Ptr(false), WebDAVEnabled: hcloud.Ptr(false), ZFSEnabled: hcloud.Ptr(false), }, SSHKeys: []*hcloud.SSHKey{ {PublicKey: "ssh-rsa AAAjjk76kgf...Xt"}, }, }) err = client.Action.WaitFor(ctx, result.Action) storageBox := result.StorageBox } Status:201 Status:4xx Status:5xx { "storage_box": { "id": 42, "status": "initializing", "name": "my-resource", "username": "u45321", "storage_box_type": { "id": 1, "name": "bx20", "description": "BX20", "snapshot_limit": 10, "automatic_snapshot_limit": 10, "subaccounts_limit": 100, "size": 1073741824, "prices": [ { "location": "fsn1", "price_hourly": { "gross": "0.0061", "net": "0.0051" }, "price_monthly": { "gross": "3.8080", "net": "3.2000" }, "setup_fee": { "gross": "0.0000", "net": "0.0000" } } ], "deprecation": null }, "location": { "id": 1, "country": "DE", "city": "Falkenstein", "name": "fsn1", "network_zone": "eu-central", "latitude": 50.476119, "longitude": 12.370071, "description": "Falkenstein DC Park 1" }, "access_settings": { "reachable_externally": false, "samba_enabled": false, "ssh_enabled": false, "webdav_enabled": false, "zfs_enabled": false }, "server": null, "system": null, "stats": { "size": 0, "size_data": 0, "size_snapshots": 0 }, "labels": { "environment": "prod", "example.com/my": "label", "just-a-key": "" }, "protection": { "delete": false }, "snapshot_plan": null, "created": "2016-01-30T23:50:00Z" }, "action": { "id": 13, "command": "create", "status": "running", "progress": 0, "started": "2016-01-30T23:50:00Z", "finished": null, "resources": [ { "id": 42, "type": "storage_box" } ], "error": null } } Get a Storage Box​Copy link Returns a specific Storage Box. Path Parameters idCopy link to id Type:integer Format:int64 min: 1 max: 9007199254740991 required Example ID of the Storage Box. Responses 200 Request succeeded. application/json 4xx Request failed with a user error. application/json 5xx Request failed with a server error. application/json Request Example for get /storage_boxes/{id} Go package examples import ( "context" "os" "github.com/hetznercloud/hcloud-go/v2/hcloud" ) func main() { token := os.Getenv("HCLOUD_TOKEN") client := hcloud.NewClient(hcloud.WithToken(token)) ctx := context.TODO() storageBox, _, err := client.StorageBox.GetByID(ctx, 123) } Status:200 Status:4xx Status:5xx { "storage_box": { "id": 42, "name": "string", "storage_box_type": { "id": 42, "name": "bx11", "description": "BX11", "snapshot_limit": 10, "automatic_snapshot_limit": 10, "subaccounts_limit": 200, "size": 1073741824, "prices": [ { "location": "fsn1", "price_hourly": { "net": "1.0000", "gross": "1.1900" }, "price_monthly": { "net": "1.0000", "gross": "1.1900" }, "setup_fee": { "net": "1.0000", "gross": "1.1900" } } ], "deprecation": { "unavailable_after": "2023-09-01T00:00:00Z", "announced": "2023-06-01T00:00:00Z" } }, "location": { "id": 42, "name": "fsn1", "description": "Falkenstein DC Park 1", "country": "DE", "city": "Falkenstein", "latitude": 50.47612, "longitude": 12.370071, "network_zone": "eu-central" }, "access_settings": { "reachable_externally": true, "samba_enabled": true, "ssh_enabled": true, "webdav_enabled": true, "zfs_enabled": true }, "snapshot_plan": { "max_snapshots": 10, "minute": 30, "hour": 3, "day_of_week": 7, "day_of_month": null }, "protection": { "delete": false }, "labels": { "environment": "prod", "example.com/my": "label", "just-a-key": "" }, "status": "active", "username": "u12345", "server": "u1337.your-storagebox.de", "system": "FSN1-BX355", "stats": { "size": 1, "size_data": 1, "size_snapshots": 1 }, "created": "2016-01-30T23:55:00Z" } } Update a Storage Box​Copy link Updates a Storage Box. Path Parameters idCopy link to id Type:integer Format:int64 min: 1 max: 9007199254740991 required Example ID of the Storage Box. Body required application/json labelsCopy link to labels Type:object Example User-defined labels (key/value pairs) for the Resource. Note that the set of Labels provided in the request will overwrite the existing one. For more information, see "Labels". Show Child Attributesfor labels nameCopy link to name Type:string Name of the Storage Box. Responses 200 Request succeeded. application/json 4xx Request failed with a user error. application/json 5xx Request failed with a server error. application/json Request Example for put /storage_boxes/{id} Go package examples import ( "context" "os" "github.com/hetznercloud/hcloud-go/v2/hcloud" ) func main() { token := os.Getenv("HCLOUD_TOKEN") client := hcloud.NewClient(hcloud.WithToken(token)) ctx := context.TODO() storageBox, _, err := client.StorageBox.Update(ctx, &hcloud.StorageBox{ID: 123}, hcloud.StorageBoxUpdateOpts{ Name: "string", Labels: map[string]string{ "environment": "prod", "example.com/my": "label", "just-a-key": "", }, }) } Status:200 Status:4xx Status:5xx { "storage_box": { "id": 42, "name": "string", "storage_box_type": { "id": 42, "name": "bx11", "description": "BX11", "snapshot_limit": 10, "automatic_snapshot_limit": 10, "subaccounts_limit": 200, "size": 1073741824, "prices": [ { "location": "fsn1", "price_hourly": { "net": "1.0000", "gross": "1.1900" }, "price_monthly": { "net": "1.0000", "gross": "1.1900" }, "setup_fee": { "net": "1.0000", "gross": "1.1900" } } ], "deprecation": { "unavailable_after": "2023-09-01T00:00:00Z", "announced": "2023-06-01T00:00:00Z" } }, "location": { "id": 42, "name": "fsn1", "description": "Falkenstein DC Park 1", "country": "DE", "city": "Falkenstein", "latitude": 50.47612, "longitude": 12.370071, "network_zone": "eu-central" }, "access_settings": { "reachable_externally": true, "samba_enabled": true, "ssh_enabled": true, "webdav_enabled": true, "zfs_enabled": true }, "snapshot_plan": { "max_snapshots": 10, "minute": 30, "hour": 3, "day_of_week": 7, "day_of_month": null }, "protection": { "delete": false }, "labels": { "environment": "prod", "example.com/my": "label", "just-a-key": "" }, "status": "active", "username": "u12345", "server": "u1337.your-storagebox.de", "system": "FSN1-BX355", "stats": { "size": 1, "size_data": 1, "size_snapshots": 1 }, "created": "2016-01-30T23:55:00Z" } } Delete a Storage Box​Copy link Deletes a Storage Box. Path Parameters idCopy link to id Type:integer Format:int64 min: 1 max: 9007199254740991 required Example ID of the Storage Box. Responses 201 Request succeeded. application/json 4xx Request failed with a user error. application/json 5xx Request failed with a server error. application/json Request Example for delete /storage_boxes/{id} Go package examples import ( "context" "os" "github.com/hetznercloud/hcloud-go/v2/hcloud" ) func main() { token := os.Getenv("HCLOUD_TOKEN") client := hcloud.NewClient(hcloud.WithToken(token)) ctx := context.TODO() result, _, err := client.StorageBox.Delete(ctx, &hcloud.StorageBox{ID: 123}) err = client.Action.WaitFor(ctx, result.Action) } Status:201 Status:4xx Status:5xx { "action": { "id": 13, "command": "delete", "status": "success", "progress": 0, "started": "2016-01-30T23:50:00Z", "finished": null, "resources": [ { "id": 42, "type": "storage_box" } ], "error": null } } List folders of a Storage Box​Copy link Returns a list of (sub)folders in a Storage Box. The folder location is specified by the path query parameter. Path Parameters idCopy link to id Type:integer Format:int64 min: 1 max: 9007199254740991 required Example ID of the Storage Box. Query Parameters pathCopy link to path Type:string default: "." Example Relative path for which the listing is to be made. Responses 200 Request succeeded. application/json 4xx Request failed with a user error. application/json 5xx Request failed with a server error. application/json Request Example for get /storage_boxes/{id}/folders Go package examples import ( "context" "os" "github.com/hetznercloud/hcloud-go/v2/hcloud" ) func main() { token := os.Getenv("HCLOUD_TOKEN") client := hcloud.NewClient(hcloud.WithToken(token)) ctx := context.TODO() result, _, err := client.StorageBox.Folders(ctx, &hcloud.StorageBox{ID: 123}, hcloud.StorageBoxFoldersOpts{ Path: ".", }) folders := result.Folders } Status:200 Status:4xx Status:5xx { "folders": [ "offsite-backup", "photos" ] } Storage Box Actions (Collapsed)​Copy link Storage Box ActionsOperations get /storage_boxes/actions get /storage_boxes/actions/{id} get /storage_boxes/{id}/actions get /storage_boxes/{id}/actions/{action_id} post /storage_boxes/{id}/actions/change_protection post /storage_boxes/{id}/actions/change_type post /storage_boxes/{id}/actions/reset_password post /storage_boxes/{id}/actions/update_access_settings post /storage_boxes/{id}/actions/rollback_snapshot post /storage_boxes/{id}/actions/disable_snapshot_plan post /storage_boxes/{id}/actions/enable_snapshot_plan Show More Storage Box Subaccounts (Collapsed)​Copy link You can create additional users for a Storage Box. FTP, FTPS, SFTP, SCP, SMB/CIFS, HTTPS, and WebDAV are all available as protocols for these users. Additional Subaccounts can only access a sub-directory of the main user, and they use the storage space of the main user. The main user will have complete access to the directories of all Subaccounts. To access a Subaccount, you use the Subaccount's username and the domain of the Subaccount (e.g uXXXXX-subX.your-storagebox.de) instead of the main account's username. It is possible to grant a Subaccount only read-access to a directory which prevents it from uploading, deleting, and modifying files. Please note that each Subaccount requires its own authorized_keys file. You can find more detailed instructions here. The home directory of a Subaccount may only contain the following characters: a‑z, A‑Z, 0‑9, dots (.), slashes (/), underscores (_) and minus signs (-). It must also not begin with a slash. Nested sub‑directories are supported. Any required directories are created automatically if they do not yet exist. Please note that you can only delete a Subaccount's home directory if you have already deleted the Subaccount itself. Storage Box SubaccountsOperations get /storage_boxes/{id}/subaccounts post /storage_boxes/{id}/subaccounts get /storage_boxes/{id}/subaccounts/{subaccount_id} put /storage_boxes/{id}/subaccounts/{subaccount_id} delete /storage_boxes/{id}/subaccounts/{subaccount_id} Show More Storage Box Subaccount Actions (Collapsed)​Copy link Storage Box Subaccount ActionsOperations post /storage_boxes/{id}/subaccounts/{subaccount_id}/actions/change_home_directory post /storage_boxes/{id}/subaccounts/{subaccount_id}/actions/reset_subaccount_password post /storage_boxes/{id}/subaccounts/{subaccount_id}/actions/update_access_settings Show More Storage Box Snapshots (Collapsed)​Copy link Storage Box SnapshotsOperations get /storage_boxes/{id}/snapshots post /storage_boxes/{id}/snapshots get /storage_boxes/{id}/snapshots/{snapshot_id} put /storage_boxes/{id}/snapshots/{snapshot_id} delete /storage_boxes/{id}/snapshots/{snapshot_id} Show More Storage Box Types (Collapsed)​Copy link Storage Box Types define storage products of different sizes. Each type has an hourly and a monthly cost. You will pay whichever cost is lower for your usage of this specific Storage Box. Costs may differ between Locations. All prices are displayed in the currency of the project owner's account. Storage Box TypesOperations get /storage_box_types get /storage_box_types/{id} Show More ============================================================ ============================================================== https://docs.hetzner.cloud/reference/cloud reference for Api docs: hetzner.cloud ============================================================== Hetzner Cloud API API Reference Changelog What's New Docs Tutorials api.hetzner.cloud Open SearchSearch Keyboard Shortcut:Command⌘ k Actions Servers Volumes Floating IPs Firewalls Load Balancers Networks DNS Security Locations Billing Hetzner Cloud API Overview This is the official documentation for the Hetzner Cloud API. Introduction The Hetzner Cloud API operates over HTTPS and uses JSON as its data format. The API is a RESTful API and utilizes HTTP methods and HTTP status codes to specify requests and responses. As an alternative to working directly with our API you may also consider to use: Our CLI program hcloud Our library for Go Our library for Python You can find even more libraries, tools and integrations on our Awesome List on GitHub. Open source credits If you are developing an open-source project that supports or intends to add support for Hetzner APIs, you may be eligible for a free one-time credit of up to € 50 / $ 50 on your account. Please contact us via the support page on your Hetzner Console and let us know the following: The name of the project you are working on A short description of the project Link to the project website or repo where the project is hosted Affiliation with / role in the project (e.g. project maintainer) Link to some other open-source work you have already done (if you have done so) Note: We only consider rewards for projects that provide Hetzner-specific functionality or integrations. For example, our Object Storage exposes a standard S3 API without any Hetzner-specific extensions. Projects that focus solely on generic S3 capabilities (e.g., general S3 clients or SDKs) are not Hetzner-specific and are therefore not eligible for Hetzner Rewards. Getting Started To get started using the API you first need an API token. Sign in into the Hetzner Console choose a Project, go to Security → API Tokens, and generate a new token. Make sure to copy the token because it won’t be shown to you again. A token is bound to a Project, to interact with the API of another Project you have to create a new token inside the Project. Let’s say your new token is LRK9DAWQ1ZAEFSrCNEEzLCUwhYX1U3g7wMg4dTlkkDC96fyDuyJ39nVbVjCKSDfj. You’re now ready to do your first request against the API. To get a list of all Servers in your Project, issue the example request on the right side using curl. Make sure to replace the token in the example command with the token you have just created. Since your Project probably does not contain any Servers yet, the example response will look like the response on the right side. We will almost always provide a resource root like servers inside the example response. A response can also contain a meta object with information like Pagination. Example Request curl -H "Authorization: Bearer LRK9DAWQ1ZAEFSrCNEEzLCUwhYX1U3g7wMg4dTlkkDC96fyDuyJ39nVbVjCKSDfj" \ https://api.hetzner.cloud/v1/servers Example Response { "servers": [], "meta": { "pagination": { "page": 1, "per_page": 25, "previous_page": null, "next_page": null, "last_page": 1, "total_entries": 0 } } } Authentication All requests to the Hetzner Cloud API must be authenticated via a API token. Include your secret API token in every request you send to the API with the Authorization HTTP header. To create a new API token for your Project, switch into the Hetzner Console choose a Project, go to Security → API Tokens, and generate a new token. Example Authorization header Authorization: Bearer LRK9DAWQ1ZAEFSrCNEEzLCUwhYX1U3g7wMg4dTlkkDC96fyDuyJ39nVbVjCKSDfj Query Parameters The API makes use of query parameters to sort and filter responses. The parameter names and values must be URI encoded according to RFC2396. Query parameters of type array can be used multiple times: Example query parameters for pagination https://api.hetzner.cloud/v1/certificates?page=1&page_size=12 Example use of multiple values for a parameter https://api.hetzner.cloud/v1/certificates?type=uploaded&type=managed Example use of an encoded parameter https://api.hetzner.cloud/v1/certificates?label_selector=key%3Dvalue Errors Errors are indicated by HTTP status codes. Further, the response of the request which generated the error contains an error code, an error message, and, optionally, error details. The schema of the error details object depends on the error code. The error response contains the following keys: Keys Meaning code Short string indicating the type of error (machine-parsable) message Textual description on what has gone wrong details An object providing for details on the error (schema depends on code) Example response { "error": { "code": "invalid_input", "message": "invalid input in field 'broken_field': is too long", "details": { "fields": [ { "name": "broken_field", "messages": ["is too long"] } ] } } } Error Codes Status Code Description 400 json_error Invalid JSON input in your request. 401 unauthorized Request was made with an invalid or unknown token. 401 token_readonly The token is only allowed to perform GET requests. 403 forbidden Insufficient permissions for this request. 403 maintenance Cannot perform operation due to maintenance. 403 resource_limit_exceeded Error when exceeding the maximum quantity of a resource for an account. 404 not_found Entity not found. 405 method_not_allowed The request method is not allowed 409 uniqueness_error One or more of the objects fields must be unique. 409 conflict The resource has changed during the request, please retry. 410 deprecated_api_endpoint The API endpoint functionality was removed. 412 resource_unavailable The requested resource is currently unavailable (e.g. not available for order). 422 invalid_input Error while parsing or processing the input. 422 service_error Error within a service. 422 unsupported_error The corresponding resource does not support the Action. 423 locked The item you are trying to access is locked (there is already an Action running). 423 protected The Action you are trying to start is protected for this resource. 429 rate_limit_exceeded Error when sending too many requests. 500 server_error Error within the API backend. 502 bad_gateway The request could not be answered by the API backend, please retry. 503 unavailable A service or product is currently not available. 504 timeout The request could not be answered in time, please retry. invalid_input { "error": { "code": "invalid_input", "message": "invalid input in field 'broken_field': is too long", "details": { "fields": [ { "name": "broken_field", "messages": ["is too long"] } ] } } } uniqueness_error { "error": { "code": "uniqueness_error", "message": "SSH key with the same fingerprint already exists", "details": { "fields": [ { "name": "public_key" } ] } } } resource_limit_exceeded { "error": { "code": "resource_limit_exceeded", "message": "project limit exceeded", "details": { "limits": [ { "name": "project_limit" } ] } } } deprecated_api_endpoint { "error": { "code": "deprecated_api_endpoint", "message": "API functionality was removed", "details": { "announcement": "https://docs.hetzner.cloud/changelog#2023-07-20-foo-endpoint-is-deprecated" } } } Actions Actions represent asynchronous tasks within the API, targeting one or more resources. Triggering changes in the API may return a running action. An action should be waited upon, until it reaches either the success or error state. Avoid polling the action's state too frequently to reduce the risk of exhausting your API requests and hitting the rate limit. If an action fails, it will contain details about the underlying error. Once the asynchronous tasks have completed and the targeted resources are in a consistent state, the action is marked as succeeded. In some cases, you may trigger multiple changes at once, and only wait for the returned actions at a later stage. Labels Labels are key/value pairs that can be attached to all resources. Valid label keys have two segments: an optional prefix and name, separated by a slash (/). The name segment is required and must be a string of 63 characters or less, beginning and ending with an alphanumeric character ([a-z0-9A-Z]) with dashes (-), underscores (_), dots (.), and alphanumerics between. The prefix is optional. If specified, the prefix must be a DNS subdomain: a series of DNS labels separated by dots (.), not longer than 253 characters in total, followed by a slash (/). Valid label values must be a string of 63 characters or less and must be empty or begin and end with an alphanumeric character ([a-z0-9A-Z]) with dashes (-), underscores (_), dots (.), and alphanumerics between. The hetzner.cloud/ prefix is reserved and cannot be used. Example Labels { "labels": { "environment": "development", "service": "backend", "example.com/my": "label", "just-a-key": "" } } Label Selector For resources with labels, you can filter resources by their labels using the label selector query language. Expression Meaning k==v / k=v Value of key k does equal value v k!=v Value of key k does not equal value v k Key k is present !k Key k is not present k in (v1,v2,v3) Value of key k is v1, v2, or v3 k notin (v1,v2,v3) Value of key k is neither v1, nor v2, nor v3 k1==v,!k2 Value of key k1 is v and key k2 is not present Examples Returns all resources that have a env=production label and that don't have a type=database label: env=production,type!=database Returns all resources that have a env=testing or env=staging label: env in (testing,staging) Returns all resources that don't have a type label: !type Pagination Responses which return multiple items support pagination. If they do support pagination, it can be controlled with following query string parameters: A page parameter specifies the page to fetch. The number of the first page is 1. A per_page parameter specifies the number of items returned per page. The default value is 25, the maximum value is 50 except otherwise specified in the documentation. Responses contain a Link header with pagination information. Additionally, if the response body is JSON and the root object is an object, that object has a pagination object inside the meta object with pagination information: Example Pagination { "servers": [...], "meta": { "pagination": { "page": 2, "per_page": 25, "previous_page": 1, "next_page": 3, "last_page": 4, "total_entries": 100 } } } The keys previous_page, next_page, last_page, and total_entries may be null when on the first page, last page, or when the total number of entries is unknown. Example Pagination Link header Link: ; rel="prev", ; rel="next", ; rel="last" Line breaks have been added for display purposes only and responses may only contain some of the above rel values. Rate Limiting All requests, whether they are authenticated or not, are subject to rate limiting. If you have reached your limit, your requests will be handled with a 429 Too Many Requests error. Burst requests are allowed. Responses contain several headers which provide information about your current rate limit status. The RateLimit-Limit header contains the total number of requests you can perform per hour. The RateLimit-Remaining header contains the number of requests remaining in the current rate limit time frame. The RateLimit-Reset header contains a UNIX timestamp of the point in time when your rate limit will have recovered, and you will have the full number of requests available again. The default limit is 3600 requests per hour and per Project. The number of remaining requests increases gradually. For example, when your limit is 3600 requests per hour, the number of remaining requests will increase by 1 every second. Server Metadata Your Server can discover metadata about itself by doing a HTTP request to specific URLs. The following data is available: Data Format Contents hostname text Name of the Server as set in the api instance-id number ID of the server public-ipv4 text Primary public IPv4 address private-networks yaml Details about the private networks the Server is attached to availability-zone text Name of the availability zone that Server runs in region text Network zone, e.g. eu-central Example: Summary $ curl http://169.254.169.254/hetzner/v1/metadata availability-zone: hel1-dc2 hostname: my-server instance-id: 42 public-ipv4: 1.2.3.4 region: eu-central Example: Hostname $ curl http://169.254.169.254/hetzner/v1/metadata/hostname my-server Example: Instance ID $ curl http://169.254.169.254/hetzner/v1/metadata/instance-id 42 Example: Public IPv4 $ curl http://169.254.169.254/hetzner/v1/metadata/public-ipv4 1.2.3.4 Example: Private Networks $ curl http://169.254.169.254/hetzner/v1/metadata/private-networks - ip: 10.0.0.2 alias_ips: [10.0.0.3, 10.0.0.4] interface_num: 1 mac_address: 86:00:00:2a:7d:e0 network_id: 1234 network_name: nw-test1 network: 10.0.0.0/8 subnet: 10.0.0.0/24 gateway: 10.0.0.1 - ip: 192.168.0.2 alias_ips: [] interface_num: 2 mac_address: 86:00:00:2a:7d:e1 network_id: 4321 network_name: nw-test2 network: 192.168.0.0/16 subnet: 192.168.0.0/24 gateway: 192.168.0.1 Example: Availability Zone $ curl http://169.254.169.254/hetzner/v1/metadata/availability-zone hel1-dc2 Example: Region $ curl http://169.254.169.254/hetzner/v1/metadata/region eu-central Sorting Some responses which return multiple items support sorting. If they do support sorting the documentation states which fields can be used for sorting. You specify sorting with the sort query string parameter. You can sort by multiple fields. You can set the sort direction by appending :asc or :desc to the field name. By default, ascending sorting is used. Example: Sorting https://api.hetzner.cloud/v1/actions?sort=status https://api.hetzner.cloud/v1/actions?sort=status:asc https://api.hetzner.cloud/v1/actions?sort=status:desc https://api.hetzner.cloud/v1/actions?sort=status:asc&sort=command:desc Deprecation Notices You can find all announced deprecations in our Changelog. Actions ​Copy link Actions represent asynchronous tasks within the API, targeting one or more resources. See Actions for more details. ActionsOperations get /actions get /actions/{id} Get multiple Actions​Copy link Returns multiple Action objects specified by the id parameter. Note: This endpoint previously allowed listing all actions in the project. This functionality was deprecated in July 2023 and removed on 30 January 2025. Announcement: https://docs.hetzner.cloud/changelog#2023-07-20-actions-list-endpoint-is-deprecated Removal: https://docs.hetzner.cloud/changelog#2025-01-30-listing-arbitrary-actions-in-the-actions-list-endpoint-is-removed Query Parameters idCopy link to id Type:array integer[] required Example Filter the actions by ID. May be used multiple times. The response will only contain actions matching the specified IDs. Responses 200 Request succeeded. application/json 4xx Request failed with a user error. application/json 5xx Request failed with a server error. application/json Request Example for get /actions Go package examples import ( "context" "os" "github.com/hetznercloud/hcloud-go/v2/hcloud" ) func main() { token := os.Getenv("HCLOUD_TOKEN") client := hcloud.NewClient(hcloud.WithToken(token)) ctx := context.TODO() actions, err := client.Action.AllWithOpts(ctx, hcloud.ActionListOpts{ID: []int64{123, 456}}) } Status:200 Status:4xx Status:5xx { "actions": [ { "id": 42, "command": "start_resource", "status": "running", "started": "2016-01-30T23:55:00Z", "finished": "2016-01-30T23:55:00Z", "progress": 100, "resources": [ { "id": 42, "type": "server" } ], "error": { "code": "action_failed", "message": "Action failed" } } ] } Get an Action​Copy link Returns a specific Action object. Path Parameters idCopy link to id Type:integer Format:int64 min: 1 max: 9007199254740991 required Example ID of the Action. Responses 200 Request succeeded. application/json 4xx Request failed with a user error. application/json 5xx Request failed with a server error. application/json Request Example for get /actions/{id} Go package examples import ( "context" "os" "github.com/hetznercloud/hcloud-go/v2/hcloud" ) func main() { token := os.Getenv("HCLOUD_TOKEN") client := hcloud.NewClient(hcloud.WithToken(token)) ctx := context.TODO() action, _, err := client.Action.GetByID(ctx, 123) } Status:200 Status:4xx Status:5xx { "action": { "id": 42, "command": "start_resource", "status": "running", "started": "2016-01-30T23:55:00Z", "finished": "2016-01-30T23:55:00Z", "progress": 100, "resources": [ { "id": 42, "type": "server" } ], "error": { "code": "action_failed", "message": "Action failed" } } } Servers (Collapsed)​Copy link Servers are virtual machines that can be provisioned. ServersOperations get /servers post /servers get /servers/{id} put /servers/{id} delete /servers/{id} get /servers/{id}/metrics Show More Server Actions (Collapsed)​Copy link Server ActionsOperations get /servers/actions get /servers/actions/{id} get /servers/{id}/actions post /servers/{id}/actions/add_to_placement_group post /servers/{id}/actions/attach_iso post /servers/{id}/actions/attach_to_network post /servers/{id}/actions/change_alias_ips post /servers/{id}/actions/change_dns_ptr post /servers/{id}/actions/change_protection post /servers/{id}/actions/change_type post /servers/{id}/actions/create_image post /servers/{id}/actions/detach_from_network post /servers/{id}/actions/detach_iso post /servers/{id}/actions/disable_backup post /servers/{id}/actions/disable_rescue post /servers/{id}/actions/enable_backup post /servers/{id}/actions/enable_rescue post /servers/{id}/actions/poweroff post /servers/{id}/actions/poweron post /servers/{id}/actions/reboot post /servers/{id}/actions/rebuild post /servers/{id}/actions/remove_from_placement_group post /servers/{id}/actions/request_console post /servers/{id}/actions/reset post /servers/{id}/actions/reset_password post /servers/{id}/actions/shutdown get /servers/{id}/actions/{action_id} Show More Server Types (Collapsed)​Copy link Server types define kinds of Servers offered. Each type has an hourly and a monthly cost. You will pay whichever cost is lower for your usage of this specific Server. Costs may differ between Locations. All prices are displayed in the currency of the project owner's account. Server TypesOperations get /server_types get /server_types/{id} Show More Images (Collapsed)​Copy link Images are blueprints for your VM disks. They can be of different types: System Images Distribution Images maintained by us, e.g. “Ubuntu 20.04” Snapshot Images Maintained by you, for example “Ubuntu 20.04 with my own settings”. These are billed per GB per month. Backup Images Daily Backups of your Server. Will automatically be created for Servers which have backups enabled (POST /servers/{id}/actions/enable_backup) Bound to exactly one Server. If you delete the Server, you also delete all backups bound to it. You may convert backup Images to snapshot Images to keep them. These are billed at 20% of your server price for 7 backup slots. App Images Prebuild images with specific software configurations, e.g. “Wordpress”. All app images are created by us. ImagesOperations get /images get /images/{id} put /images/{id} delete /images/{id} Show More Image Actions (Collapsed)​Copy link Image ActionsOperations get /images/actions get /images/actions/{id} get /images/{id}/actions post /images/{id}/actions/change_protection get /images/{id}/actions/{action_id} Show More ISOs (Collapsed)​Copy link ISOs are read-only Images of DVDs. While we recommend using our Image functionality to install your Servers we also provide some stock ISOs so you can install more exotic operating systems by yourself. On request our support uploads a private ISO just for you. These are marked with type private and only visible in your Project. To attach an ISO to your Server use POST /servers/{id}/actions/attach_iso. ISOsOperations get /isos get /isos/{id} Show More Placement Groups (Collapsed)​Copy link Placement groups are used to influence the location of interdependent virtual servers in our data centers. The distribution of the different servers within a group is based on a pattern specified in the type. By enforcing certain rules on the placement of servers within our infrastructure, availability can be influenced in a way that fits your needs best. In spread placement groups, all virtual servers will run on different physical servers. This decreases the probability that some servers might fail together. Placement GroupsOperations get /placement_groups post /placement_groups get /placement_groups/{id} put /placement_groups/{id} delete /placement_groups/{id} Show More Primary IPs (Collapsed)​Copy link Primary IPs help you to create more flexible networking setups. You can assign at most one Primary IP of type ipv4 and one of type ipv6 per Server. This Server then uses these IPs. You can only unassign a Primary IP from a Server when it's powered off. This Primary IP can then be assigned to a different powered off Server, or you can keep it around for later use. Primary IPs are bound to a specific Location. You can not assign a Primary IP from one Location to a Server in a different Location. If you need this capability use Floating IPs instead. If your Server's operating system supports cloud-init there is no further configuration needed to make Primary IPs work. Primary IPs of type ipv4 use a single IPv4 address as their ip property. Primary IPs of type ipv6 use a /64 network such as fc00::/64 as their ip property. Any IP address within that network can be used on your host. Primary IPs are billed on an hourly basis. Primary IPsOperations get /primary_ips post /primary_ips get /primary_ips/{id} put /primary_ips/{id} delete /primary_ips/{id} Show More Primary IP Actions (Collapsed)​Copy link Primary IP ActionsOperations get /primary_ips/actions get /primary_ips/actions/{id} get /primary_ips/{id}/actions get /primary_ips/{id}/actions/{action_id} post /primary_ips/{id}/actions/assign post /primary_ips/{id}/actions/change_dns_ptr post /primary_ips/{id}/actions/change_protection post /primary_ips/{id}/actions/unassign Show More Volumes (Collapsed)​Copy link A Volume is a highly-available, scalable, and SSD-based block storage for Servers. Pricing for Volumes depends on the Volume size and Location, not the actual used storage. Please see Hetzner Docs for more details about Volumes. VolumesOperations get /volumes post /volumes get /volumes/{id} put /volumes/{id} delete /volumes/{id} Show More Volume Actions (Collapsed)​Copy link Volume ActionsOperations get /volumes/actions get /volumes/actions/{id} get /volumes/{id}/actions post /volumes/{id}/actions/attach post /volumes/{id}/actions/change_protection post /volumes/{id}/actions/detach post /volumes/{id}/actions/resize get /volumes/{id}/actions/{action_id} Show More Floating IPs (Collapsed)​Copy link Floating IPs help you to create highly available setups. You can assign a Floating IP to any Server. The Server can then use this IP. You can reassign it to a different Server at any time, or you can choose to unassign the IP from Servers all together. Floating IPs can be used globally. This means you can assign a Floating IP to a Server in one Location and later reassign it to a Server in a different Location. For optimal routing and latency Floating IPs should be used in the Location they were created in. For Floating IPs to work with your Server, you must configure them inside your operation system. Floating IPs of type ipv4 use a single IPv4 address as their ip property. Floating IPs of type ipv6 use a /64 network such as fc00::/64 as their ip property. Any IP address within that network can be used on your host. Floating IPs are billed on a monthly basis. Floating IPsOperations get /floating_ips post /floating_ips get /floating_ips/{id} put /floating_ips/{id} delete /floating_ips/{id} Show More Floating IP Actions (Collapsed)​Copy link Floating IP ActionsOperations get /floating_ips/actions get /floating_ips/actions/{id} get /floating_ips/{id}/actions post /floating_ips/{id}/actions/assign post /floating_ips/{id}/actions/change_dns_ptr post /floating_ips/{id}/actions/change_protection post /floating_ips/{id}/actions/unassign get /floating_ips/{id}/actions/{action_id} Show More Firewalls (Collapsed)​Copy link Firewalls can limit the network access to or from your resources. When applying a firewall with no in rule all inbound traffic will be dropped. The default for in is DROP. When applying a firewall with no out rule all outbound traffic will be accepted. The default for out is ACCEPT. FirewallsOperations get /firewalls post /firewalls get /firewalls/{id} put /firewalls/{id} delete /firewalls/{id} Show More Firewall Actions (Collapsed)​Copy link Firewall ActionsOperations get /firewalls/actions get /firewalls/actions/{id} get /firewalls/{id}/actions post /firewalls/{id}/actions/apply_to_resources post /firewalls/{id}/actions/remove_from_resources post /firewalls/{id}/actions/set_rules get /firewalls/{id}/actions/{action_id} Show More Load Balancers (Collapsed)​Copy link Load BalancersOperations get /load_balancers post /load_balancers get /load_balancers/{id} put /load_balancers/{id} delete /load_balancers/{id} get /load_balancers/{id}/metrics Show More Load Balancer Actions (Collapsed)​Copy link Load Balancer ActionsOperations get /load_balancers/actions get /load_balancers/actions/{id} get /load_balancers/{id}/actions post /load_balancers/{id}/actions/add_service post /load_balancers/{id}/actions/add_target post /load_balancers/{id}/actions/attach_to_network post /load_balancers/{id}/actions/change_algorithm post /load_balancers/{id}/actions/change_dns_ptr post /load_balancers/{id}/actions/change_protection post /load_balancers/{id}/actions/change_type post /load_balancers/{id}/actions/delete_service post /load_balancers/{id}/actions/detach_from_network post /load_balancers/{id}/actions/disable_public_interface post /load_balancers/{id}/actions/enable_public_interface post /load_balancers/{id}/actions/remove_target post /load_balancers/{id}/actions/update_service get /load_balancers/{id}/actions/{action_id} Show More Load Balancer Types (Collapsed)​Copy link Load Balancer types define kinds of Load Balancers offered. Each type has an hourly and a monthly cost. You will pay whichever amount is lower for your usage of this specific Load Balancer. Costs may differ between Locations. All prices are displayed in the currency of the project owner's account. Load Balancer TypesOperations get /load_balancer_types get /load_balancer_types/{id} Show More Networks (Collapsed)​Copy link Networks is a private networks feature. These Networks are optional and they coexist with the public network that every Server has by default. They allow Servers to talk to each other over a dedicated network interface using private IP addresses not available publicly. The IP addresses are allocated and managed via the API, they must conform to RFC1918 standard. IPs and network interfaces defined under Networks do not provide public internet connectivity, you will need to use the already existing public network interface for that. Each network has a user selected ip_range which defines all available IP addresses which can be used for Subnets within the Network. To assign individual IPs to Servers you will need to create Network Subnets, described below. Currently Networks support IPv4 only. Subnets Subnets divide the ip_range from the parent Network object into multiple Subnetworks that you can use for different specific purposes. For each subnet you need to specify its own ip_range which must be contained within the parent Network’s ip_range. Additionally each subnet must belong to one of the available Network Zones described below. Subnets can not have overlapping IP ranges. Currently there are three types of subnet: type cloud is used to connect cloud Resources into your Network. type server was used to connect only cloud Servers into your Network. This type is deprecated and is replaced by type cloud. type vswitch allows you to connect Dedicated Server vSwitch - and all Dedicated Servers attached to it - into your Network Subnets of type vswitch must set a vswitch_id which is the ID of the existing vSwitch in Hetzner Robot that should be coupled. Network Zones Network Zones are groups of Locations which have special high-speed network connections between them. The Location object contains the network_zone property each Location belongs to. Currently these network zones exist: Network Zone Contains Locations eu-central nbg1, fsn1, hel1 us-east ash us-west hil ap-southeast sin IP address management When a cloud Server is attached to a network without the user specifying an IP it automatically gets an IP address assigned from a subnet of type server in the same network zone. If you specify the optional ip parameter when attaching then we will try to assign that IP. Keep in mind that the Server’s location must be covered by the Subnet’s Network Zone if you specify an IP, or that at least one Subnet with the zone covering Server’s location must exist. A cloud Server can also have more than one IP address in a Network by specifying aliases. For details see the attach to network action. The following IP addresses are reserved in networks and can not be used: the first IP of the network ip_range as it will be used as a default gateway for the private Network interface. 172.31.1.1 as it is being used as default gateway for our public Network interfaces. Coupling Dedicated Servers By using subnets of type vswitch you can couple the Cloud Networks with an existing Dedicated Server vSwitch and enable dedicated and cloud servers to talk to each other over the Network. In order for this to work the dedicated servers may only use IPs from the subnet and must have a special network configuration. Please refer to FAQ. vSwitch Layer 2 features are not supported. Routes Networks also support the notion of routes which are automatically applied to private traffic. A route makes sure that all packets for a given destination IP prefix will be sent to the address specified in its gateway. NetworksOperations get /networks post /networks get /networks/{id} put /networks/{id} delete /networks/{id} Show More Network Actions (Collapsed)​Copy link Network ActionsOperations get /networks/actions get /networks/actions/{id} get /networks/{id}/actions post /networks/{id}/actions/add_route post /networks/{id}/actions/add_subnet post /networks/{id}/actions/change_ip_range post /networks/{id}/actions/change_protection post /networks/{id}/actions/delete_route post /networks/{id}/actions/delete_subnet get /networks/{id}/actions/{action_id} Show More Zones (Collapsed)​Copy link A Zone represents a Domain Name System (DNS) zone managed by Hetzner authoritative nameservers. Please see Hetzner Docs for the difference between zones and domains. This API supports all zone names with well-known public suffixes (e.g. .de, .com, .co.uk). Subdomains are not supported. Zone Modes This API supports two types of zone modes. In primary mode, resource record sets (RRSets) and resource records (RRs) are managed via the Cloud API or Hetzner Console. In secondary mode, Hetzner's nameservers query RRSets and RRs from given primary nameservers via AXFR. The zone mode cannot be changed, the zone must be deleted and re-created with a new mode. SOA Serial For zones in primary mode, Hetzner automatically increases the SOA record serial number. As convention, a YYYYMMDDnn format with incrementing nn is used. Zone file import This API supports importing a zone file in BIND (RFC 1034/1035) format. Importing a zone file is only applicable for Zones in primary mode. During an import: An $ORIGIN directive may be present, it must match the Zone's name with an ending dot A $TTL directive may be present, it is used as new default Zone Time To Live (TTL) Only IN (internet) class records are allowed The assigned authoritative Hetzner nameservers must be present as NS records A SOA record must be present Comments are discarded Zone file example: $ORIGIN example.com. $TTL 3600 @ IN SOA hydrogen.ns.hetzner.com. dns.hetzner.com. 2024010100 86400 10800 3600000 3600 @ IN 10800 NS hydrogen.ns.hetzner.com. ; Some comment. @ IN 10800 NS oxygen.ns.hetzner.com. @ IN 10800 NS helium.ns.hetzner.de. ZonesOperations get /zones post /zones get /zones/{id_or_name} put /zones/{id_or_name} delete /zones/{id_or_name} get /zones/{id_or_name}/zonefile Show More Zone Actions (Collapsed)​Copy link Zone ActionsOperations get /zones/actions get /zones/actions/{id} get /zones/{id_or_name}/actions get /zones/{id_or_name}/actions/{action_id} post /zones/{id_or_name}/actions/change_primary_nameservers post /zones/{id_or_name}/actions/change_protection post /zones/{id_or_name}/actions/change_ttl post /zones/{id_or_name}/actions/import_zonefile Show More Zone RRSets (Collapsed)​Copy link This API operates on resource record sets (RRSets) instead of individual resource records (RRs). An RRSet is identified by a name and type. For example, the two RRs (name: @, type: MX, value: 10 smtp.example.com.) and (name: @, type: MX, value: 20 smtp-backup.example.com.) are part of the RRSet identified by (name: @, type: MX). Please see Hetzner Docs for more information on types. Zone RRSetsOperations get /zones/{id_or_name}/rrsets post /zones/{id_or_name}/rrsets get /zones/{id_or_name}/rrsets/{rr_name}/{rr_type} put /zones/{id_or_name}/rrsets/{rr_name}/{rr_type} delete /zones/{id_or_name}/rrsets/{rr_name}/{rr_type} Show More Zone RRSet Actions (Collapsed)​Copy link Zone RRSet ActionsOperations post /zones/{id_or_name}/rrsets/{rr_name}/{rr_type}/actions/change_protection post /zones/{id_or_name}/rrsets/{rr_name}/{rr_type}/actions/change_ttl post /zones/{id_or_name}/rrsets/{rr_name}/{rr_type}/actions/set_records post /zones/{id_or_name}/rrsets/{rr_name}/{rr_type}/actions/add_records post /zones/{id_or_name}/rrsets/{rr_name}/{rr_type}/actions/remove_records post /zones/{id_or_name}/rrsets/{rr_name}/{rr_type}/actions/update_records Show More Certificates (Collapsed)​Copy link TLS/SSL Certificates prove the identity of a Server and are used to encrypt client traffic. CertificatesOperations get /certificates post /certificates get /certificates/{id} put /certificates/{id} delete /certificates/{id} Show More Certificate Actions (Collapsed)​Copy link Certificate ActionsOperations get /certificates/actions get /certificates/actions/{id} get /certificates/{id}/actions post /certificates/{id}/actions/retry get /certificates/{id}/actions/{action_id} Show More SSH Keys (Collapsed)​Copy link SSH keys are public keys you provide to the cloud system. They can be injected into Servers at creation time. We highly recommend that you use keys instead of passwords to manage your Servers. SSH KeysOperations get /ssh_keys post /ssh_keys get /ssh_keys/{id} put /ssh_keys/{id} delete /ssh_keys/{id} Show More Locations (Collapsed)​Copy link Datacenters are organized by Locations. Datacenters in the same Location are connected with very low latency links. LocationsOperations get /locations get /locations/{id} Show More Data Centers (Collapsed)​Copy link Each Datacenter represents a virtual Datacenter which may consist of possibly many physical Datacenters. A physical Datacenter is where Servers are hosted. See the Hetzner Locations Docs for more details about Datacenters. Data CentersOperations get /datacenters get /datacenters/{id} Show More Pricing (Collapsed)​Copy link Returns prices for resources. PricingOperations get /pricing Get all prices​Copy link Returns prices for all resources available on the platform. VAT and currency of the Project owner are used for calculations. Both net and gross prices are included in the response. Responses 200 Request succeeded. application/json 4xx Request failed with a user error. application/json 5xx Request failed with a server error. application/json Request Example for get /pricing Go package examples import ( "context" "os" "github.com/hetznercloud/hcloud-go/v2/hcloud" ) func main() { token := os.Getenv("HCLOUD_TOKEN") client := hcloud.NewClient(hcloud.WithToken(token)) ctx := context.TODO() pricing, _, err := client.Pricing.Get(ctx) } Status:200 Status:4xx Status:5xx { "pricing": { "currency": "EUR", "vat_rate": "19.00", "primary_ips": [ { "type": "ipv4", "prices": [ { "location": "fsn1", "price_hourly": { "net": "1.0000", "gross": "1.1900" }, "price_monthly": { "net": "1.0000", "gross": "1.1900" } } ] } ], "floating_ips": [ { "type": "ipv4", "prices": [ { "location": "fsn1", "price_monthly": { "net": "1.0000", "gross": "1.1900" } } ] } ], "image": { "price_per_gb_month": { "net": "1.0000", "gross": "1.1900" } }, "volume": { "price_per_gb_month": { "net": "1.0000", "gross": "1.1900" } }, "server_backup": { "percentage": "20.00" }, "server_types": [ { "id": 104, "name": "cpx22", "prices": [ { "location": "fsn1", "price_hourly": { "net": "1.0000", "gross": "1.1900" }, "price_monthly": { "net": "1.0000", "gross": "1.1900" }, "included_traffic": 654321, "price_per_tb_traffic": { "net": "1.0000", "gross": "1.1900" } } ] } ], "load_balancer_types": [ { "id": 1, "name": "lb11", "prices": [ { "location": "fsn1", "price_hourly": { "net": "1.0000", "gross": "1.1900" }, "price_monthly": { "net": "1.0000", "gross": "1.1900" }, "included_traffic": 654321, "price_per_tb_traffic": { "net": "1.0000", "gross": "1.1900" } } ] } ] } } ===============================================================